<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
    <title>LuaCov - Coverage analysis for Lua scripts</title>
    <link rel="stylesheet" href="doc.css" type="text/css" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<style type="text/css">
pre {
   font-family: "Andale Mono", monospace;
}
div.Example {
   font-family: "Andale Mono", monospace;
   background-color: #f0f0f0;
   margin-left: 1em;
   margin-right: 1em;
   margin-top: 0.5em;
   margin-bottom 0.5em;
   padding: 0.5em;
}
</style>
</head>

<body>

<div id="container">
    
<div id="product">
    <div id="product_logo"><a href="http://luacov.luaforge.net">
        <img alt="LuaCov logo" src="luacov.png" />
    </a></div>
    <div id="product_name"><big><strong>LuaCov</strong></big></div>
    <div id="product_description">Coverage analysis for Lua scripts</div>
</div> <!-- id="product" -->

<div id="main">

<div id="navigation">

<h1>LuaCov</h1>

<ul>
    <li><strong>Home</strong>
        <ul>
            <li> <a href="index.html#over">Overview</a></li>
            <li> <a href="index.html#download">Download</a></li>
            <li> <a href="index.html#instructions">Instructions</a></li>
            <li> <a href="index.html#history">History</a></li>
            <li> <a href="index.html#credits">Credits</a></li>
            <li> <a href="index.html#contact">Contact</a></li>
        </ul>
    </li>
    <li><a href="http://luaforge.net/projects/luacov/">Project</a>
        <ul>
            <li><a href="http://luaforge.net/scm/?group_id=290">CVS</a></li>
        </ul>
    </li>
    <li><a href="license.html">License</a></li>
</ul>

</div> <!-- id="navigation" -->

<div id="content">

<h2><a name="over"></a>Overview</h2>

<p>
LuaCov is a simple coverage analyzer for <a href="http://www.lua.org">Lua</a>
scripts. When a Lua script is run with the <tt>luacov</tt> module loaded, it
generates a stats file with the number of executions of each line of the
script and its loaded modules. The <tt>luacov</tt> command-line script then
processes this file generating a report file which allows one to visualize
which code paths were not traversed, which is useful for verifying the
effectiveness of a test suite.
</p>

<p>
LuaCov is free software and uses the same <a href="license.html">license</a> as Lua.
</p>

<h2><a name="download"></a>Download</h2>

<p>
LuaCov can be downloaded from its
<a href="http://luaforge.net/projects/luacov/files/">LuaForge page</a>.
</p>

<p>
LuaCov is written in pure Lua and has no external dependencies.
</p>

<h2><a name="instructions"></a>Instructions</h2>

<p>
Using LuaCov consists of two steps: running your script to collect
coverage data, and then running <tt>luacov</tt> on the collected data to
generate a report.
</p>

<p>
To collect coverage data, your script needs to load the <tt>luacov</tt>
Lua module. This can be done from the command-line, without modifying
your script, like this:
</p>

<div class="Example">
lua -lluacov test.lua
</div>

<p>
(Alternatively, you can add <tt>require("luacov")</tt> to the first line
of your script.)
</p>

<p>
Once the script is run, a file called <tt>lcov.stats.out</tt> is generated.
If the file already exists, statistics are <i>added</i> to it. This is useful,
for example, for making a series of runs with different input parameters in
a test suite. To start the accounting from scratch, just delete the stats file.
</p>

<p>
To generate a report, just run the <tt>luacov</tt> command-line script.
It expects to find a file named <tt>lcov.stats.out</tt> in the current
directory, and outputs a file named <tt>lcov.report.out</tt>.
</p>

<p>This is an example output of the report file:</p>

<div class="Example"><pre>
============================================================
../test.lua
============================================================

        -- Which branch will run?
1       if 10 > 100 then
0          print("I don't think this line will execute.")
0       else
1          print("Hello, LuaCov!")
1       end
</pre></div>

<p>
Note that to generate this report, <tt>luacov</tt> reads the source files.
Therefore, it expects to find them in the same location they were when
the <tt>luacov</tt> module ran (the stats file stores the filenames, but
not the sources themselves).
</p>

<p>
LuaCov saves its stats upon normal program termination. If your program
is a daemon -- in other words, if it does not terminate normally -- you
can use the <tt>luacov.tick</tt> module, which periodically saves the
stats file. For example, to run (on Unix systems) LuaCov on
<a href="http://www.keplerproject.org/xavante">Xavante</a>,
just modify the first line of <tt>xavante_start.lua</tt> so it reads:
</p>

<div class="Example">
#!/usr/bin/env lua -lluacov.tick
</div>

<h2><a name="history"></a>History</h2>

<dl>
    <dt><strong>0.1</strong> [July 16, 2007]</dt>
    <dd>
        <ul>
            <li>Initial release.</li>
        </ul>
    </dd>
</dl>

<h2><a name="credits"></a>Credits</h2>

<p>
LuaCov was designed and implemented by Hisham Muhammad as a tool for
testing <a href="http://luarocks.luaforge.net">LuaRocks</a>.
</p>

<h2><a name="contact"></a>Contact</h2>

<p>
For more information please
<a href="mailto:hisham-NO-SPAM-THANKS@gobolinux.org">contact</a> us. Comments are welcome!
</p>

</div> <!-- id="content" -->

</div> <!-- id="main" -->

<div id="about">
    <p><a href="http://validator.w3.org/check?uri=referer">
    <img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
</div> <!-- id="about" -->

</div> <!-- id="container" -->

</body>
</html>
